OpenEuphoria

[[ updating oE has_console ]]\\\\
[[ updating oE key_codes ]]\\\\
[[ updating oE KC_LBUTTON ]]\\\\
[[ updating oE set_keycodes ]]\\\\
[[ updating oE NO_CURSOR ]]\\\\
[[ updating oE UNDERLINE_CURSOR ]]\\\\
[[ updating oE THICK_UNDERLINE_CURSOR ]]\\\\
[[ updating oE HALF_BLOCK_CURSOR ]]\\\\
[[ updating oE BLOCK_CURSOR ]]\\\\
[[ updating oE get_key ]]\\\\
[[ updating oE allow_break ]]\\\\
[[ updating oE check_break ]]\\\\
[[ updating oE wait_key ]]\\\\
[[ updating oE any_key ]]\\\\
[[ updating oE maybe_any_key ]]\\\\
[[ updating oE prompt_number ]]\\\\
[[ updating oE prompt_string ]]\\\\
[[ updating oE positive_int ]]\\\\
[[ updating oE clear_screen ]]\\\\
[[ updating oE get_screen_char ]]\\\\
[[ updating oE put_screen_char ]]\\\\
[[ updating oE attr_to_colors ]]\\\\
[[ updating oE colors_to_attr ]]\\\\
[[ updating oE display_text_image ]]\\\\
[[ updating oE save_text_image ]]\\\\
[[ updating oE text_rows ]]\\\\
[[ updating oE cursor ]]\\\\
[[ updating oE free_console ]]\\\\
[[ updating oE display ]]\\\\

== Console

<<LEVELTOC level=2 depth=4>>


=== Information


@[:console:has_console|]
==== has_console
<eucode>
include console.e
namespace console
public function has_console()
</eucode>

determines if the process has a console (terminal) window.

===== Returns:
An **atom**,
* ##1## if there is more than one process attached to the current console,
* ##0## if a console does not exist or only one process (Euphoria) is attached to
the current console.

===== Comments:
* On //Unix// systems always returns ##1## .
* On //Windows// client systems earlier than Windows XP the function always returns ##0## .
* On //Windows// server systems earlier than Windows Server 2003 the function always returns ##0## .

===== Example 1:
<eucode>
include std/console.e

if has_console() then
printf(1, "Hello Console!")
end if
</eucode>



@[:console:key_codes|]
==== key_codes
<eucode>
include console.e
namespace console
public function key_codes(object codes = 0)
</eucode>

gets and sets the keyboard codes used internally by Euphoria.

===== Parameters:
# ##codes## : Either a sequence of exactly 256 integers or an atom (the default).

===== Returns:
A **sequence**,
of the current 256 keyboard codes, prior to any changes that
this function might make.

===== Comments:
When ##codes## is a atom then no change to the existing codes is made, otherwise
the set of 256 integers in ##codes## completely replaces the existing codes.

===== Example 1:
<eucode>
include std/console.e
sequence kc
kc = key_codes() -- Get existing set.
kc[KC_LEFT] = 263 -- Change the code for the left-arrow press.
key_codes(kc) -- Set the new codes.
</eucode>



=== Key Code Names
These are the names of the index values for each of the 256 key code values.


===== See Also:
[[:key_codes]]


@[:console:KC_LBUTTON|]
==== KC_LBUTTON
<eucode>
include console.e
namespace console
public constant KC_LBUTTON
</eucode>





@[:console:set_keycodes|]
==== set_keycodes
<eucode>
include console.e
namespace console
public function set_keycodes(object kcfile)
</eucode>

changes the default codes returned by the keyboard.

===== Parameters:
# ##kcfile## : Either the name of a text file or the handle of an opened (for reading) text file.

===== Returns:
An **integer**,
* ##0## means no error.
* ##-1## means that the supplied file could not me loaded in to a [[:map]].
* ##-2## means that a new key value was not an integer.
* ##-3## means that an unknown key name was found in the file.

===== Comments:
The text file is expected to contain bindings for one or more keyboard codes.

The format of the files is a set of lines, one line per key binding, in the
form ##KEYNAME = NEWVALUE##. The ##KEYNAME## is the same as the constants but without
the "##KC_##" prefix. The key bindings can be in any order.

===== Example 1:
{{{
-- doskeys.txt file containing some key bindings
F1 = 260
F2 = 261
INSERT = 456
}}}
<eucode>
set_keycodes( "doskeys.txt" )
</eucode>

===== See Also:
[[:key_codes]]


=== Cursor Style Constants

In cursor constants the second and fourth hex digits (from the
left) determine the top and bottom row of pixels in the cursor. The first
digit controls whether the cursor will be visible or not. For example~: ###0407##
turns on the 4th through 7th rows.

Note: //Windows// only.

===== See Also:
[[:cursor]]


@[:console:NO_CURSOR|]
==== NO_CURSOR
<eucode>
include console.e
namespace console
public constant NO_CURSOR
</eucode>





@[:console:UNDERLINE_CURSOR|]
==== UNDERLINE_CURSOR
<eucode>
include console.e
namespace console
public constant UNDERLINE_CURSOR
</eucode>





@[:console:THICK_UNDERLINE_CURSOR|]
==== THICK_UNDERLINE_CURSOR
<eucode>
include console.e
namespace console
public constant THICK_UNDERLINE_CURSOR
</eucode>





@[:console:HALF_BLOCK_CURSOR|]
==== HALF_BLOCK_CURSOR
<eucode>
include console.e
namespace console
public constant HALF_BLOCK_CURSOR
</eucode>





@[:console:BLOCK_CURSOR|]
==== BLOCK_CURSOR
<eucode>
include console.e
namespace console
public constant BLOCK_CURSOR
</eucode>





=== Keyboard Related Routines


@[:eu:get_key|]
==== get_key
<eucode>
<built-in> function get_key()
</eucode>

returns the key that was pressed by the user, without waiting. Special
codes are returned for the function keys, arrow keys, and so on.

===== Returns:
An **integer**,
either -1 if no key waiting, or the code of the next key
waiting in keyboard buffer.

===== Comments:
The operating system can hold a small number of key-hits in its keyboard buffer.
##get_key## will return the next one from the buffer, or ##-1## if the buffer is empty.

Run the ##.../euphoria/demo/key.ex## program to see what key code is generated for each key on your
keyboard.

===== Example 1:
<eucode>
integer n = get_key()
if n=-1 then
puts(1, "No key waiting.\n")
end if
</eucode>

===== See Also:
[[:wait_key]]


@[:console:allow_break|]
==== allow_break
<eucode>
include console.e
namespace console
public procedure allow_break(types :boolean b)
</eucode>

sets the behavior of Control+C and Control+Break keys.

===== Parameters:
# ##b## : a boolean, TRUE ( != 0 ) to enable the trapping of
Control+C and Control+Break, FALSE ( 0 ) to disable it.

===== Comments:
When ##b## is ##1## (true), Control+C and Control+Break can terminate
your program when it tries to read input from the keyboard. When
##b## is ##0## (false) your program will not be terminated by Control+C or Control+Break.

Initially your program can be terminated at any point where
it tries to read from the keyboard.

You can find out if the user has pressed Control+C or Control+Break by calling
[[:check_break]].

===== Example 1:
<eucode>
allow_break(0) -- don't let the user kill the program!
</eucode>

===== See Also:
[[:check_break]]


@[:console:check_break|]
==== check_break
<eucode>
include console.e
namespace console
public function check_break()
</eucode>

returns the number of Control+C and Control+Break key presses.

===== Returns:
An **integer**,
the number of times that Control+C or Control+Break have
been pressed since the last call to ##check_break##, or since the
beginning of the program if this is the first call.

===== Comments:
This is useful after you have called [[:allow_break]](0) which
prevents Control+C or Control+Break from terminating your
program. You can use ##check_break## to find out if the user
has pressed one of these keys. You might then perform some action
such as a graceful shutdown of your program.

Neither Control+C nor Control+Break will be returned as input
characters when you read the keyboard. You can only detect
them by calling ##check_break##.

===== Example 1:
<eucode>
k = get_key()
if check_break() then -- ^C or ^Break was hit once or more
temp = graphics_mode(-1)
puts(STDOUT, "Shutting down...")
save_all_user_data()
abort(1)
end if
</eucode>

===== See Also:
[[:allow_break]]


@[:console:wait_key|]
==== wait_key
<eucode>
include console.e
namespace console
public function wait_key()
</eucode>

waits for user to press a key, unless any is pending, and returns key code.

===== Returns:
An **integer**,
which is a key code. If one is waiting in keyboard buffer, then return it. Otherwise, wait for one to come up.

===== See Also:
[[:get_key]], [[:getc]]


@[:console:any_key|]
==== any_key
<eucode>
include console.e
namespace console
public procedure any_key(sequence prompt = "Press Any Key to continue...", integer con = 1)
</eucode>

displays a prompt to the user and waits for any key.

===== Parameters:
# ##prompt## : Prompt to display, defaults to ##"Press Any Key to continue..."## .
# ##con## : Either ##1## (stdout), or ##2## (stderr). Defaults to ##1## .

===== Comments:
This wraps [[:wait_key]] by giving a clue that the user should press a key, and
perhaps do some other things as well.

===== Example 1:
<eucode>
any_key() -- "Press Any Key to continue..."
</eucode>

===== Example 2:
<eucode>
any_key("Press Any Key to quit")
</eucode>

===== See Also:
[[:wait_key]]


@[:console:maybe_any_key|]
==== maybe_any_key
<eucode>
include console.e
namespace console
public procedure maybe_any_key(sequence prompt = "Press Any Key to continue...",
integer con = 1)
</eucode>

displays a prompt to the user and waits for any key. //Only// if the user is
running under a GUI environment.

===== Parameters:
# ##prompt## : Prompt to display, defaults to ##"Press Any Key to continue..."##
# ##con## : Either 1 (stdout), or 2 (stderr). Defaults to 1.

===== Comments:
This wraps [[:wait_key]] by giving a clue that the user should press a key, and
perhaps do some other things as well.

Requires Windows XP or later or Windows 2003 or later to work. Earlier versions of //Windows//
or O/S will always pause even when not needed.

On //Unix// systems this will not pause even when needed.

===== Example 1:
<eucode>
any_key() -- "Press Any Key to continue..."
</eucode>

===== Example 2:
<eucode>
any_key("Press Any Key to quit")
</eucode>

===== See Also:
[[:wait_key]]


@[:console:prompt_number|]
==== prompt_number
<eucode>
include console.e
namespace console
public function prompt_number(sequence prompt, sequence range)
</eucode>

prompts the user to enter a number and returns only validated input.

===== Parameters:
# ##st## : is a string of text that will be displayed on the screen.
# ##s## : is a sequence of two values {lower, upper} which determine the range of values
that the user may enter. s can be empty, {}, if there are no restrictions.

===== Returns:
An **atom**,
in the assigned range which the user typed in.

===== Errors:
If [[:puts]] cannot display ##st## on standard output, or if the first or second element
of ##s## is a sequence, a runtime error will be raised.

If user tries cancelling the prompt by hitting Control+Z, the program will abort as well,
issuing a type check error.

===== Comments:
As long as the user enters a number that is less than lower or greater
than upper, the user will be prompted again.

If this routine is too simple for your needs, feel free to copy it and make your
own more specialized version.

===== Example 1:
<eucode>
age = prompt_number("What is your age? ", {0, 150})
</eucode>

===== Example 2:
<eucode>
t = prompt_number("Enter a temperature in Celcius:\n", {})
</eucode>

===== See Also:
[[:puts]], [[:prompt_string]]



@[:console:prompt_string|]
==== prompt_string
<eucode>
include console.e
namespace console
public function prompt_string(sequence prompt)
</eucode>

prompts the user to enter a string of text.

===== Parameters:
# ##st## : is a string that will be displayed on the screen.

===== Returns:
A **sequence**,
the string that the user typed in, stripped of any new-line character.

===== Comments:
If the user happens to type Control+Z (indicates end-of-file), "" will be returned.

===== Example 1:
<eucode>
name = prompt_string("What is your name? ")
</eucode>

===== See Also:
[[:prompt_number]]


=== Cross Platform Text Graphics


@[:console:positive_int|]
==== positive_int
<eucode>
include console.e
namespace console
public type positive_int(object x)
</eucode>



@[:eu:clear_screen|]
==== clear_screen
<eucode>
<built-in> procedure clear_screen()
</eucode>

clears the screen using the current background color.

===== Comments:
The background color can be set by [[:bk_color]] ).

===== See Also:
[[:bk_color]]



@[:console:get_screen_char|]
==== get_screen_char
<eucode>
include console.e
namespace console
public function get_screen_char(positive_atom line, positive_atom column, integer fgbg = 0)
</eucode>

gets the value and attribute of the character at a given screen location.

===== Parameters:
# ##line## : the 1-base line number of the location.
# ##column## : the 1-base column number of the location.
# ##fgbg## : an integer, if ##0## (the default) you get an attribute_code
returned otherwise you get a foreground and background color
number returned.

===== Returns:
* If fgbg is zero then a **sequence** of //two// elements, ##{character, attribute_code}##
for the specified location.
* If fgbg is not zero then a **sequence** of //three// elements, ##{characterfg_color, bg_color}##.

===== Comments:
* This function inspects a single character on the //active page//.
* The attribute_code is an atom that contains the foreground and background
color of the character, and possibly other operating-system dependant
information describing the appearance of the character on the screen.
* With ##get_screen_char## and ##put_screen_char## you can save and restore
a character on the screen along with its attribute_code.
* The ##fg_color## and ##bg_color## are integers in the range ##0## to ##15## which correspond
to the values in the table~:

Color Table

|= color number |= name |
| 0 | black |
| 1 | dark blue |
| 2 | green |
| 3 | cyan |
| 4 | crimson |
| 5 | purple |
| 6 | brown |
| 7 | light gray |
| 8 | dark gray |
| 9 | blue |
| 10 | bright green |
| 11 | light blue |
| 12 | red |
| 13 | magenta |
| 14 | yellow |
| 15 | white |


===== Example 1:
<eucode>
-- read character and attributes at top left corner
s = get_screen_char(1,1)
-- s could be {'A', 92}
-- store character and attributes at line 25, column 10
put_screen_char(25, 10, s)
</eucode>

===== Example 2:
<eucode>
-- read character and colors at line 25, column 10.
s = get_screen_char(25,10, 1)
-- s could be {'A', 12, 5}
</eucode>

===== See Also:
[[:put_screen_char]], [[:save_text_image]]


@[:console:put_screen_char|]
==== put_screen_char
<eucode>
include console.e
namespace console
public procedure put_screen_char(positive_atom line, positive_atom column, sequence char_attr)
</eucode>

stores and displays a sequence of characters with attributes at a given location.

===== Parameters:
# ##line## : the 1-based line at which to start writing.
# ##column## : the 1-based column at which to start writing.
# ##char_attr## : a sequence of alternated characters and attribute codes.

===== Comments:

##char_attr## must be in the form ##{character, attribute code, character, attribute code, ...}##.

===== Errors:
The length of ##char_attr## must be a multiple of two.

===== Comments:

The attributes atom contains the foreground color, background color, and possibly other platform-dependent information controlling how the character is displayed on the screen.
If ##char_attr## has ##0## length, nothing will be written to the screen. The characters are written to the //active page//.
It is faster to write several characters to the screen with a single call to ##put_screen_char## than it is to write one character at a time.

===== Example 1:
<eucode>
-- write AZ to the top left of the screen
-- (attributes are platform-dependent)
put_screen_char(1, 1, {'A', 152, 'Z', 131})
</eucode>

===== See Also:
[[:get_screen_char]], [[:display_text_image]]


@[:console:attr_to_colors|]
==== attr_to_colors
<eucode>
include console.e
namespace console
public function attr_to_colors(integer attr_code)
</eucode>

converts an attribute code to its foreground and background color components.

===== Parameters:
# ##attr_code## : integer, an attribute code.

===== Returns:
A **sequence**,
of two elements ~-- ##{fgcolor, bgcolor}##

===== Example 1:
<eucode>
? attr_to_colors(92) --> {12, 5}
</eucode>

===== See Also:
[[:get_screen_char]], [[:colors_to_attr]]


@[:console:colors_to_attr|]
==== colors_to_attr
<eucode>
include console.e
namespace console
public function colors_to_attr(object fgbg, integer bg = 0)
</eucode>

converts a foreground and background color set to its attribute code format.

===== Parameters:
# ##fgbg## : Either a sequence of ##{fgcolor, bgcolor}## or just an integer fgcolor.
# ##bg## : An integer bgcolor. Only used when ##fgbg## is an integer.

===== Returns:
An **integer**,
an attribute code.

===== Example 1:
<eucode>
? colors_to_attr({12, 5}) --> 92
? colors_to_attr(12, 5) --> 92
</eucode>

===== See Also:
[[:get_screen_char]], [[:put_screen_char]], [[:attr_to_colors]]


@[:console:display_text_image|]
==== display_text_image
<eucode>
include console.e
namespace console
public procedure display_text_image(text_point xy, sequence text)
</eucode>

displays a text image in any text mode.

===== Parameters:
# ##xy## : a pair of 1-based coordinates representing the point at which to start writing.
# ##text## : a list of sequences of alternated character and attribute.

===== Comments:
This routine displays to the active text page, and only works in text modes.

You might use [[:save_text_image]] and [[:display_text_image]] in a text-mode graphical
user interface, to allow "pop-up" dialog boxes, and drop-down menus to appear and disappear
without losing what was previously on the screen.

===== Example 1:
<eucode>
clear_screen()
display_text_image({1,1}, {{'A', WHITE, 'B', GREEN},
{'C', RED+16*WHITE},
{'D', BLUE}})
-- displays:
-- AB
-- C
-- D
-- at the top left corner of the screen.
-- 'A' will be white with black (0) background color,
-- 'B' will be green on black,
-- 'C' will be red on white, and
-- 'D' will be blue on black.
</eucode>

===== See Also:
[[:save_text_image]], [[:put_screen_char]]



@[:console:save_text_image|]
==== save_text_image
<eucode>
include console.e
namespace console
public function save_text_image(text_point top_left, text_point bottom_right)
</eucode>

copies a rectangular block of text out of screen memory.

===== Parameters:
# ##top_left## : the coordinates, given as a pair, of the upper left corner of the area to save.
# ##bottom_right## : the coordinates, given as a pair, of the lower right corner of the area to save.

===== Returns:
A **sequence**,
of ##{character, attribute, character, ...}## lists.

===== Comments:

The returned value is appropriately handled by [[:display_text_image]].

This routine reads from the active text page, and only works in text modes.

You might use this function in a text-mode graphical user interface to save a portion of the
screen before displaying a drop-down menu, dialog box, alert box, and so on.

===== Example 1:
<eucode>
-- Top 2 lines are: Hello and World
s = save_text_image({1,1}, {2,5})

-- s is something like: {"H-e-l-l-o-", "W-o-r-l-d-"}
</eucode>

===== See Also:
[[:display_text_image]], [[:get_screen_char]]


@[:console:text_rows|]
==== text_rows
<eucode>
include console.e
namespace console
public function text_rows(positive_int rows)
</eucode>

sets the number of lines on a text-mode screen.

===== Parameters:
# ##rows## : an integer, the desired number of rows.

===== Platform:
//Windows//

===== Returns:
An **integer**,
the actual number of text lines.

===== Comments:
Values of 25, 28, 43 and 50 lines are supported by most video cards.

===== See Also:

[[:graphics_mode]], [[:video_config]]


@[:console:cursor|]
==== cursor
<eucode>
include console.e
namespace console
public procedure cursor(integer style)
</eucode>

selects a style of cursor.

===== Parameters:
# ##style## : an integer defining the cursor shape.

===== Platform:
//Windows//

===== Comments:

In pixel-graphics modes no cursor is displayed.

===== Example 1:
<eucode>
cursor(BLOCK_CURSOR)
</eucode>

Cursor Type Constants~:
* [[:NO_CURSOR]]
* [[:UNDERLINE_CURSOR]]
* [[:THICK_UNDERLINE_CURSOR]]
* [[:HALF_BLOCK_CURSOR]]
* [[:BLOCK_CURSOR]]

===== See Also:
[[:graphics_mode]], [[:text_rows]]



@[:console:free_console|]
==== free_console
<eucode>
include console.e
namespace console
public procedure free_console()
</eucode>

frees (deletes) any console window associated with your program.

===== Comments:
Euphoria will create a console text window for your program the first time that your
program prints something to the screen, reads something from the keyboard, or in some
way needs a console. On //Windows// this window will automatically disappear when your program
terminates, but you can call ##free_console## to make it disappear sooner. On //Unix//
the text mode console is always there, but an xterm window will disappear after Euphoria
issues a ##"Press Enter"## prompt at the end of execution.

On //Unix// ##free_console## will set the terminal parameters back to normal,
undoing the effect that curses has on the screen.

In a //Unix// terminal a call to ##free_console## (without any further
printing to the screen or reading from the keyboard) will eliminate the
"Press Enter" prompt that Euphoria normally issues at the end of execution.

After freeing the console window, you can create a new console window by printing
something to the screen, calling ##clear_screen##, ##position##, or any other
routine that needs a console.

When you use the trace facility, or when your program has an error, Euphoria will
automatically create a console window to display trace information, error messages, and so on.

There is a WINDOWS API routine, {{{FreeConsole()}}} that does something similar to
##free_console##. Use the Euphoria ##free_console## because it lets the interpreter know
that there is no longer a console to write to or read from.

===== See Also:
[[:clear_screen]]


@[:console:display|]
==== display
<eucode>
include console.e
namespace console
public procedure display(object data_in, object args = 1, integer finalnl = - 918_273_645)
</eucode>

displays the supplied data on the console screen at the current cursor position.

===== Parameters:
# ##data_in## : Any object.
# ##args## : Optional arguments used to format the output. Default is ##1## .
# ##finalnl## : Optional. Determines if a new line is output after the data.
Default is to output a new line.

===== Comments:
* If ##data_in## is an atom or integer, it is simply displayed.

* If ##data_in## is a simple text string, then ##args## can be used to
produce a formatted output with ##data_in## providing the [[:text:format]] string and
##args## being a sequence containing the data to be formatted.
** If the last character of ##data_in## is an underscore character then it
is stripped off and ##finalnl## is set to zero. Thus ensuring that a new line
is **not** output.
** The formatting codes expected in ##data_in## are the ones used by [[:text:format]].
It is not mandatory to use formatting codes, and if ##data_in## does not contain
any then it is simply displayed and anything in ##args## is ignored.

* If ##data_in## is a sequence containing floating-point numbers, sub-sequences
or integers that are not characters, then ##data_in## is forwarded on to the
[[:pretty_print]] to display.
** If ##args## is a non-empty sequence, it is assumed to contain the pretty_print formatting options.
** if ##args## is an atom or an empty sequence, the assumed pretty_print formatting
options are assumed to be ##{2}##.

After the data is displayed, the routine will normally output a New Line. If you
want to avoid this, ensure that the last parameter is a zero. Or to put this
another way, if the last parameter is zero then a New Line will **not** be output.

===== Example 1:
<eucode>
display("Some plain text")
-- Displays this string on the console plus a new line.
display("Your answer:",0)
-- Displays this string on the console without a new line.
display("cat")
display("Your answer:",,0)
-- Displays this string on the console without a new line.
display("")
display("Your answer:_")
-- Displays this string,
-- except the '_', on the console without a new line.
display("dog")
display({"abc", 3.44554})
-- Displays the contents of 'res' on the console.
display("The answer to [1] was [2]", {"'why'", 42})
-- formats these with a new line.
display("",2)
display({51,362,71}, {1})
</eucode>
Output would be~:
{{{
Some plain text
Your answer:cat
Your answer:
Your answer:dog
{
"abc",
3.44554
}
The answer to 'why' was 42
""
{51'3',362,71'G'}
}}}